/*
 * Copyright (c) 2024. hallele, Inc All rights reserved.
 */

package cn.hallele.mc.sdk.filecenter.api;

import cn.hallele.infrastructure.metadata.io.Response;
import cn.hallele.mc.sdk.filecenter.dto.FileDTO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.multipart.MultipartFile;

/**
 * 处理文件
 *
 * @author anle5
 * @since 2024/9/15 20:34
 */
@Tag(name = "01.文件管理")
public interface FileApi {
    /**
     * 文件上传接口
     *
     * @param file 待上传的文件
     * @return 地址
     */
    @Operation(summary = "文件上传接口")
    @PostMapping("/file")
    Response<String> uploadFile(@RequestParam("file") @NotNull MultipartFile file,
                                @RequestParam("action") @NotNull String action);

    /**
     * 删除文件
     *
     * @param id 文件id
     * @return 成功/失败
     */
    @Operation(summary = "删除文件")
    @DeleteMapping("/file")
    Response<Boolean> deleteFile(@RequestParam("id") @NotNull Long id);

    /**
     * 获取文件的url路径
     *
     * @param id 文件id
     * @return 文件url
     */
    @Operation(summary = "获取文件")
    @GetMapping("/file")
    Response<String> getFile(@RequestParam("id") @NotNull Long id);

    /**
     * 获取文件的url路径，供前端下载/展示，但是有过期时间
     *
     * @param id      文件id
     * @param expires 过期时间
     * @return 文件url
     */
    @Operation(summary = "获取文件")
    @GetMapping("/fileWithExpires")
    Response<String> getUrlWithExpires(@RequestParam("id") Long id,
                                       @RequestParam("expires") Integer expires);

    /**
     * 获取图片的Base64
     *
     * @param id 文件id
     * @return 文件url
     */
    @Operation(summary = "获取图片的Base64")
    @GetMapping("/img")
    Response<String> getFileBase64(@RequestParam("id") @NotNull Long id);

    /**
     * 检查文件是否存在
     *
     * @param md5 md5值
     * @return 如果存在会返回文件信息，否则返回null
     */
    @GetMapping("")
    Response<FileDTO> checkExist(@RequestParam("md5") @NotNull String md5);
}
